{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Building Multi-Agent AI Systems: From Concept to Implementation\n",
    "\n",
    "## Introduction\n",
    "\n",
    "AI systems are becoming increasingly complex, tackling problems that require multiple\n",
    "specialized capabilities working in concert. In this tutorial, we'll build a multi-agent\n",
    "system where specialized AI agents collaborate to accomplish complex tasks.\n",
    "\n",
    "We'll explore:\n",
    "1. Why multi-agent architectures are the future\n",
    "2. The challenges of building multi-agent systems\n",
    "3. How to implement a multi-agent system using mahilo\n",
    "4. Building a complex multi-agent system step-by-step\n",
    "\n",
    "The example we will showcase is a multi-agent system for filmmaking, that won the first prize in the [ElevenLabs Worldwide Hackathon](https://hackathon.elevenlabs.io/) for the Bengaluru track. Learn more about the project on our [Devpost submission page](https://devpost.com/software/879504/joins/ZK96p6ArfUi97mxjzxwkYQ)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why Multi Agent Systems?\n",
    "\n",
    "\n",
    "\n",
    "Multi-agent systems offer several key advantages:\n",
    "\n",
    "1. **Specialization**: Different agents can focus on specific tasks, leading to better\n",
    "   performance in each domain - just like specialists in a team.\n",
    "\n",
    "   ![](https://miro.medium.com/v2/resize:fit:640/format:webp/0*zf7GL-Dz8JAOB7tf.gif)\n",
    "\n",
    "2. **Task Decomposition**: Complex problems become manageable when broken down into\n",
    "   smaller sub-problems assigned to specialized agents.\n",
    "\n",
    "3. **Parallel Processing**: Multiple agents can work simultaneously on different aspects\n",
    "   of a problem, increasing efficiency.\n",
    "\n",
    "4. **Better Accuracy**: Increasing the size of the toolset for a given agent leads to a dip in accuracy as shown by the ReWOO paper.\n",
    "\n",
    "   ![](https://miro.medium.com/v2/resize:fit:640/format:webp/1*GvD5uvHY0mOPrmpp9Oh6-A.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Challenges of Building Multi-Agent Systems\n",
    "\n",
    "Despite their benefits, building effective multi-agent systems presents challenges:\n",
    "\n",
    "### 1. Communication Complexity\n",
    "\n",
    "Enabling effective communication between agents requires:\n",
    "\n",
    "- Designing protocols for agents to request information from each other\n",
    "- Ensuring messages contain appropriate context\n",
    "- Tracking conversations and maintaining state across interactions\n",
    "- Preventing infinite loops and circular references\n",
    "\n",
    "### 2. Observability Challenges\n",
    "\n",
    "As your agent system grows, understanding what's happening becomes difficult:\n",
    "\n",
    "- Tracing requests across multiple agents\n",
    "- Identifying which agent might be causing issues\n",
    "- Collecting metrics on agent performance\n",
    "- Debugging failures in a distributed system\n",
    "\n",
    "### 3. Human-in-the-Loop Complexity\n",
    "\n",
    "Integrating human oversight adds another layer of complexity:\n",
    "\n",
    "- Creating interfaces for humans to monitor agent activities\n",
    "- Designing effective handoff protocols between AI and humans\n",
    "- Determining when to escalate decisions to human operators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## mahilo: A Lightweight Control Plane for Multi-Agent Systems\n",
    "\n",
    "Mahilo is a framework designed to address these challenges while remaining lightweight\n",
    "and flexible. The following is an example of a multi-agent system in mahilo that showcases how agents within mahilo can communicate automatically while still being supervised by a human.\n",
    "\n",
    "![mahilo_arch](../../assets/mahilo.png)\n",
    "\n",
    "To understand how mahilo works, let's start by building a simple multi-agent system.\n",
    "We'll create a team of two agents:\n",
    "\n",
    "1. A **Research Agent** that can find information\n",
    "2. A **Writing Agent** that can create content based on that information\n",
    "\n",
    "First, let's define our research agent. The process for the Writing Agent will be similar and we will not show it for brevity."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setup\n",
    "Before, we begin, let's install the [mahilo](https://github.com/wjayesh/mahilo) package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install mahilo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add an OpenAI API key to the environment variables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import getpass\n",
    "import os\n",
    "\n",
    "os.environ[\"OPENAI_API_KEY\"] = getpass.getpass(\"Enter your OpenAI API key: \")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's create a basic multi-agent system with these agents, with no tools. Later on, in the Filmmaker project, we'll look at a complete implementation with tools and workflows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mahilo import BaseAgent, AgentManager, ServerManager\n",
    "\n",
    "def setup_simple_system() -> ServerManager:\n",
    "    # Create the agents\n",
    "    research_agent = BaseAgent(\n",
    "        name=\"ResearchAgent\",\n",
    "        type=\"research_agent\",\n",
    "        description=\"You are a research agent\",\n",
    "        short_description=\"A research agent\",\n",
    "        tools=[],\n",
    "    )\n",
    "    \n",
    "    writing_agent = BaseAgent(\n",
    "        name=\"WritingAgent\",\n",
    "        type=\"writing_agent\",\n",
    "        description=\"You are a writing agent\",\n",
    "        short_description=\"A writing agent\",\n",
    "        tools=[],\n",
    "        can_contact=[\"research_agent\"]  # Specify which agents this agent can contact\n",
    "    )\n",
    "    \n",
    "    # Create an agent manager to manage our team\n",
    "    team = AgentManager()\n",
    "    \n",
    "    # Register the agents with the manager\n",
    "    team.register_agent(research_agent)\n",
    "    team.register_agent(writing_agent)\n",
    "    \n",
    "    # Activate the agents\n",
    "    research_agent.activate()\n",
    "    writing_agent.activate()\n",
    "    \n",
    "    # Create a server manager to handle agent communication\n",
    "    server = ServerManager(team)\n",
    "    \n",
    "    return server"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import asyncio\n",
    "import nest_asyncio\n",
    "\n",
    "server = setup_simple_system()\n",
    "\n",
    "# run the server\n",
    "nest_asyncio.apply()\n",
    "asyncio.run(server.run())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can now connect to the server using the mahilo CLI in your terminal.This will open a chat where you can talk to the research agent about your task. The agent can then process your request and reach out to the writing agent as needed to complete the task.\n",
    "\n",
    "```bash\n",
    "mahilo connect --agent-name ResearchAgent\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What's important to notice here\n",
    "1. **Automatic Communication**: The writing agent can automatically communicate internally with the\n",
    "   research agent thanks to mahilo's communication layer.\n",
    "\n",
    "2. **Clear Separation of Concerns**: Each agent has a specific role and set of capabilities,\n",
    "   making the system modular and maintainable.\n",
    "\n",
    "3. **Simple Setup**: Despite being a multi-agent system, the setup code is straightforward\n",
    "   and easy to understand.\n",
    "\n",
    "4. **Minimal Boilerplate**: Mahilo handles all the communication infrastructure, so we can\n",
    "   focus on defining the agents' capabilities and behavior.\n",
    "\n",
    "In a real application, the server would be running, and you'd interact with it through API\n",
    "calls or a web interface. Each agent would have more sophisticated tools, and the communication\n",
    "would happen automatically as needed.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Built for complex applications\n",
    "\n",
    "In addition to the features above, mahilo boasts other features that make\n",
    "it a powerful tool for building multi-agent systems.\n",
    "\n",
    "1. Built-in Observability\n",
    "\n",
    "    Mahilo provides out-of-the-box metrics, traces (in OpenTelemetry format), and logs of all\n",
    "inter-agent communications, making it easy to understand, debug, and optimize your system.\n",
    "    #  <div style=\"display: flex; flex-direction: row; justify-content: space-between; gap: 10px;\">\n",
    "    #    <img src=\"../../assets/metrics.png\" alt=\"metrics\" style=\"max-width: 48%;\" />\n",
    "    #    <img src=\"../../assets/traces.png\" alt=\"traces\" style=\"max-width: 48%;\" />\n",
    "    #  </div>\n",
    "\n",
    "2. Inter-Agent Communication Protocol\n",
    "\n",
    "    All agents communicate using a simple protocol that has features like retries, acknowledgement, response validation and more. In addition, all messages are tracked and available at the server's `/messages` endpoint.\n",
    "\n",
    "3. Human-in-the-Loop First\n",
    "\n",
    "    Unlike many frameworks where human oversight is an afterthought, mahilo treats humans as\n",
    "first-class participants. Any agent can have a human counterpart who can monitor, intervene,\n",
    "and guide the agent as needed.\n",
    "\n",
    "3. Framework Agnostic\n",
    "\n",
    "    Mahilo is designed to work with agents from any framework, whether they're built with\n",
    "LangChain, PydanticAI, or custom implementations. This makes it easy to \n",
    "incorporate existing agents or specialized tools into your system."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Watch a demo of a mahilo system in action:\n",
    "\n",
    "[![](../../assets/mahilo_tut_simple.jpg)](https://x.com/wjayesh/status/1872263352254427458)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we understand the basics, let's move on to a more complex real-world example:\n",
    "a multi-agent system for filmmaking."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Hitchcock Project: A Multi-Agent Filmmaker\n",
    "\n",
    "Let's examine a more complex example: a multi-agent system for filmmaking\n",
    "that won the first prize in the [ElevenLabs Worldwide Hackathon](https://hackathon.elevenlabs.io/) for the Bengaluru track. This system has multiple agents that work together to output a film in the end. Here, I'll explain the thought process behind building such a system, and how I went about designing and executing it.\n",
    "\n",
    "### Step 1: Planning the System Architecture\n",
    "\n",
    "Before writing any code, it's crucial to plan the overall architecture of your multi-agent system.\n",
    "For our filmmaker project, we started by:\n",
    "\n",
    "1. **Identifying the Core Processes**: Analyzing the filmmaking process to identify distinct stages\n",
    "   that could benefit from specialization\n",
    "\n",
    "2. **Defining Agent Boundaries**: Determining clear responsibilities for each agent to avoid overlap\n",
    "   and ensure clear ownership of tasks\n",
    "\n",
    "3. **Mapping Communication Flows**: Deciding which agents need to communicate with each other\n",
    "   and what information they need to exchange\n",
    "\n",
    "4. **Designing Workflow Sequences**: Establishing the correct order of operations to produce\n",
    "   a coherent final product\n",
    "\n",
    "![hithcock_arch](../../assets/hitchcock_arch.jpg)\n",
    "\n",
    "Our analysis led us to a system with four specialized agents:\n",
    "\n",
    "1. **Script Writer Agent**: Creates the initial movie script based on a prompt\n",
    "2. **Story Boarder Agent**: Breaks down the script into visual scenes and shots\n",
    "3. **Director of Photography (DOP) Agent**: Generates images based on storyboard specifications\n",
    "4. **Audio Agent**: Creates audio content matching the visual scenes\n",
    "\n",
    "This architecture ensures that each stage of film production has a dedicated expert agent,\n",
    "with clear workflows between them.\n",
    "\n",
    "### Step 2: Designing Agent Capabilities\n",
    "\n",
    "For each agent, we needed to:\n",
    "\n",
    "1. **Define Core Competencies**: What specific tasks can this agent perform?\n",
    "2. **Design Appropriate Tools**: What functions should the agent have access to?\n",
    "3. **Craft Effective Prompts**: How should we instruct the agent to use these tools?\n",
    "4. **Establish Communication Protocols**: When and how should this agent interact with others?\n",
    "\n",
    "Let's look at how we designed the Script Writer agent:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# First, we defined the prompt that establishes the agent's role and behavior\n",
    "script_writer_prompt = \"\"\"\n",
    "You are a creative story writer agent specialized in creating movie scripts. You have access to powerful research tools:\n",
    "\n",
    "1. Web Search and Browsing:\n",
    "   - search_information: Search the internet for information\n",
    "   - visit: Visit and read web pages\n",
    "   - page_up/page_down: Navigate through long content\n",
    "   - find/find_next: Search within pages\n",
    "   - search_archives: Search historical archives\n",
    "\n",
    "2. Text Analysis:\n",
    "   - inspect_file_as_text: Analyze and extract information from text content\n",
    "\n",
    "When given a writing task:\n",
    "1. First research the historical and cultural context of your setting\n",
    "2. Study similar movies and their themes for inspiration\n",
    "3. Use the research to create authentic, well-researched scripts\n",
    "4. Pay special attention to:\n",
    "   - Dialogue matching the era and location\n",
    "   - Historically accurate scene descriptions\n",
    "   - Cultural authenticity\n",
    "   - Period-appropriate details\n",
    "\n",
    "Once you're done with the script generation, inform the story boarder agent to create a storyboard. Always do that, and you can\n",
    "use the chat_with_agent tool for it.\n",
    "\n",
    "Wait for specific requests before taking action. Use your research tools to gather information before writing.\n",
    "\"\"\"\n",
    "\n",
    "# Then, a concise description that helps other agents understand its role\n",
    "script_writer_short_description = \"\"\"\n",
    "Story writer agent for creating movie scripts with deep research capabilities\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we implemented key tools that the agent would need to fulfill its role.\n",
    "\n",
    "> Note: This is a simplified version of the actual implementation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_script_with_research(script_prompt) -> str:\n",
    "    \"\"\"\n",
    "    Generate a movie script based on the given prompt with research capabilities.\n",
    "    \n",
    "    Args:\n",
    "        script_prompt (str): Description of the script to generate\n",
    "        \n",
    "    Returns:\n",
    "        str: Generated script text\n",
    "    \"\"\"\n",
    "    # In the real implementation, this would:\n",
    "    # 1. Use a research agent to gather relevant information\n",
    "    # 2. Generate a full script using an LLM\n",
    "    # 3. Save the script to a shared location for other agents to access\n",
    "    # 4. Extract character information for the storyboard agent\n",
    "    \n",
    "    # For demonstration purposes, we'll just return a placeholder\n",
    "    return f\"Generated script based on: {script_prompt}\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The next step is to package the tool in mahilo's expected format. This is just the OpenAI tool definition spec with an additional function field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Package the tool in mahilo's expected format\n",
    "script_writer_tools = [\n",
    "    {\n",
    "        \"tool\": {\n",
    "            \"type\": \"function\",\n",
    "            \"function\": {\n",
    "                \"name\": \"get_script_with_research\",\n",
    "                \"description\": \"Generate a movie script with research capabilities\",\n",
    "                \"parameters\": {\n",
    "                    \"type\": \"object\",\n",
    "                    \"properties\": {\n",
    "                        \"script_prompt\": {\n",
    "                            \"type\": \"string\",\n",
    "                            \"description\": \"Description of the script to generate (e.g., 'Write a thriller set in 1920s Chicago')\"\n",
    "                        }\n",
    "                    },\n",
    "                    \"required\": [\"script_prompt\"]\n",
    "                }\n",
    "            }\n",
    "        },\n",
    "        \"function\": get_script_with_research,\n",
    "    }\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 3: Building Data Flow Mechanisms\n",
    "A critical aspect of multi-agent systems is ensuring data flows correctly between agents.\n",
    "For our filmmaker project, we implemented several data sharing mechanisms:\n",
    "\n",
    "1. **File-Based Sharing**: Scripts, storyboards, and generated images are saved to disk\n",
    "   where other agents can access them\n",
    "\n",
    "2. **Database Integration**: A shared database stores structured information like character\n",
    "   details, scene breakdowns, and shot specifications\n",
    "\n",
    "3. **Direct Communication**: Agents can request specific information from each other\n",
    "   using mahilo's internal communication protocol.\n",
    "\n",
    "For example, here's how our Story Boarder agent uses these mechanisms:\n",
    "1. It reads the script from a file saved by the Script Writer\n",
    "2. It processes the script and saves structured scene data to a database\n",
    "3. It notifies the DOP agent when storyboard specifications are ready\n",
    "\n",
    "This approach ensures that each agent has access to the exact information it needs,\n",
    "in the most appropriate format for its tasks. With mahilo, to make an agent talk to another agent, all you need to do is simply mention this in the prompt.\n",
    "\n",
    "Let's look at how the Story Boarder agent is programmed to drive the workflow forward:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "story_boarder_prompt = \"\"\"\n",
    "You are a professional storyboard artist agent specialized in breaking down scripts into visual elements. Your role involves two main phases:\n",
    "\n",
    "1. Initial Storyboard Creation (when receiving from Script Writer Agent):\n",
    "   a. Use plan_storyboard_scenes to break down script into scenes and mark their importance\n",
    "   b. Use analyze_script_scenes to process critical/high importance scenes and plan key shots\n",
    "   c. Use plan_visual_elements to define lighting, props, atmosphere, and effects\n",
    "   d. Use create_shot_image_specs to compile detailed specifications for the DOP agent\n",
    "\n",
    "   After completion, notify the DOP agent that the storyboard is ready.\n",
    "   Then, notify the Audio agent that the storyboard is ready and it can generate audio for the script.\n",
    "\n",
    "2. Image Review Phase (when receiving from DOP Agent):\n",
    "   - Use critique_generated_images to review and provide feedback on generated images\n",
    "   - Specify any needed adjustments\n",
    "\n",
    "Focus on:\n",
    "- Critical story-driving scenes\n",
    "- Clear, practical shot descriptions\n",
    "- Technical feasibility\n",
    "- Visual consistency\n",
    "- Complete information for DOP\n",
    "\n",
    "Only use tools when explicitly asked to analyze/design, or when DOP requests image review.\n",
    "\"\"\"\n",
    "\n",
    "story_boarder_short_description = \"\"\"\n",
    "Storyboard artist agent for breaking down scripts into visual elements\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The prompt explicitly directs the agent to notify the next agents in the workflow,\n",
    "ensuring that the process moves forward automatically."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4: Building the Control Plane\n",
    "\n",
    "With all our agents and workflows designed, the final step is creating the control plane\n",
    "that brings everything together. In mahilo, this is remarkably straightforward:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "def setup_filmmaker_system():\n",
    "    # Create the Script Writer agent\n",
    "    script_writer = BaseAgent(\n",
    "        name=\"ScriptWriterAgent\",\n",
    "        type=\"script_writer\",\n",
    "        description=script_writer_prompt,\n",
    "        short_description=script_writer_short_description,\n",
    "        tools=script_writer_tools,\n",
    "    )\n",
    "\n",
    "    # Create the Story Boarder agent\n",
    "    story_boarder = BaseAgent(\n",
    "        name=\"StoryBoarderAgent\",\n",
    "        type=\"story_boarder\",\n",
    "        description=story_boarder_prompt,\n",
    "        short_description=story_boarder_short_description,\n",
    "        tools=[], # simplified for the tutorial\n",
    "    )\n",
    "\n",
    "    # Create the DOP agent (simplified for the tutorial)\n",
    "    dop = BaseAgent(\n",
    "        name=\"DOPAgent\",\n",
    "        type=\"dop\",\n",
    "        description=\"Director of Photography agent specialized in generating images\",\n",
    "        short_description=\"Creates images based on storyboard specifications\",\n",
    "        tools=[],  # simplified for the tutorial\n",
    "    )\n",
    "\n",
    "    # Create the Audio agent (simplified for the tutorial)\n",
    "    audio = BaseAgent(\n",
    "        name=\"AudioAgent\",\n",
    "        type=\"audio\",\n",
    "        description=\"Audio agent specialized in creating sound content\",\n",
    "        short_description=\"Creates audio content matching the visual scenes\",\n",
    "        tools=[],  # simplified for the tutorial\n",
    "    )\n",
    "\n",
    "    # Create an agent manager to manage our team\n",
    "    team = AgentManager()\n",
    "    \n",
    "    # Register all agents with the manager\n",
    "    team.register_agent(script_writer)\n",
    "    team.register_agent(story_boarder)\n",
    "    team.register_agent(dop)\n",
    "    team.register_agent(audio)\n",
    "    \n",
    "    # Activate the agent you want to start chat with\n",
    "    script_writer.activate()\n",
    "    \n",
    "    # Create a server manager to handle agent communication\n",
    "    server = ServerManager(team)\n",
    "    \n",
    "    return server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 5: Running the System\n",
    "\n",
    "You can run the control plane by calling the `run` method on the server object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import asyncio\n",
    "import nest_asyncio\n",
    "\n",
    "server = setup_filmmaker_system()\n",
    "\n",
    "# run the server\n",
    "nest_asyncio.apply()\n",
    "asyncio.run(server.run())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar to the simple system, you can connect to the server using the mahilo CLI in your terminal.\n",
    "\n",
    "```bash\n",
    "mahilo connect --agent-name ScriptWriterAgent\n",
    "```\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hithcock Demo\n",
    "\n",
    "The following is a demo of the filmmaker system in action.\n",
    "\n",
    "[![Hitchcock Demo](https://img.youtube.com/vi/O0bswr-46kg/0.jpg)](https://www.youtube.com/watch?v=O0bswr-46kg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Best Practices for building multi-agent apps\n",
    "\n",
    "Based on our experience developing the filmmaker system, here are some best practices:\n",
    "\n",
    "1. Clear Agent Boundaries\n",
    "\n",
    "    Define precise, non-overlapping responsibilities for each agent.\n",
    "\n",
    "    *Why it matters*: Clear boundaries prevent confusion, reduce redundant work, and make\n",
    "the system easier to debug and maintain.\n",
    "\n",
    "2. Thoughtful Prompt Engineering\n",
    "\n",
    "    Craft detailed prompts that guide agent behavior and interaction patterns.\n",
    "\n",
    "    *Why it matters*: Well-designed prompts serve as both documentation and runtime\n",
    "instructions, ensuring agents behave as expected.\n",
    "\n",
    "3. Explicit Communication Guideliness\n",
    "\n",
    "    Establish when and how agents should communicate, including what information\n",
    "they should share.\n",
    "\n",
    "    *Why it matters*: Without protocols, agents may overwhelm each other with irrelevant\n",
    "information or fail to share critical data.\n",
    "\n",
    "4. Workflow Orchestration\n",
    "\n",
    "    Implement clear trigger patterns for moving from one stage to the next.\n",
    "\n",
    "    *Why it matters*: Without orchestration, multi-agent systems can stall or produce\n",
    "inconsistent results.\n",
    "\n",
    "5. Testing Agent Interactions\n",
    "\n",
    "    Test agent pairs in isolation before integrating them into the full system.\n",
    "\n",
    "    *Why it matters*: Isolating agent interactions makes it easier to identify and fix\n",
    "communication issues.\n",
    "\n",
    "6. Human Oversight Design\n",
    "\n",
    "    Tell the agents in their prompt about specific checkpoints where humans should review and intervene in the process.\n",
    "\n",
    "    *Why it matters*: Human oversight improves quality and provides a safety net for\n",
    "handling edge cases and creative decisions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "In this tutorial, we've explored:\n",
    "\n",
    "1. Why multi-agent architectures are essential for complex AI applications\n",
    "2. The challenges of building multi-agent systems from scratch\n",
    "3. How mahilo simplifies multi-agent development\n",
    "4. A simple example demonstrating mahilo's core capabilities\n",
    "5. A real-world case study of a prize-winning filmmaker system\n",
    "6. Best practices for developing effective multi-agent systems\n",
    "\n",
    "Multi-agent systems represent the future of AI application development, enabling more\n",
    "sophisticated, reliable, and maintainable solutions than single-agent approaches.\n",
    "With frameworks like mahilo, these powerful architectures become accessible to developers\n",
    "without requiring extensive expertise.\n",
    "\n",
    "By focusing on clear agent design, thoughtful communication patterns, and effective\n",
    "workflow orchestration, you can build multi-agent systems that tackle complex problems\n",
    "through the collaboration of specialized agents.\n",
    "\n",
    "We have a community where you can share your experiences and learn from others, feel free to join us:\n",
    "https://github.com/wjayesh/mahilo/discussions"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "multiagent",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
